home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / isc / socket.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  20.2 KB  |  766 lines
  1. /*
  2.  * Copyright (C) 2004-2006, 2008  Internet Systems Consortium, Inc. ("ISC")
  3.  * Copyright (C) 1998-2002  Internet Software Consortium.
  4.  *
  5.  * Permission to use, copy, modify, and/or distribute this software for any
  6.  * purpose with or without fee is hereby granted, provided that the above
  7.  * copyright notice and this permission notice appear in all copies.
  8.  *
  9.  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10.  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11.  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12.  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13.  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14.  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15.  * PERFORMANCE OF THIS SOFTWARE.
  16.  */
  17.  
  18. /* $Id: socket.h,v 1.57.18.6.46.4 2008/07/23 23:16:43 marka Exp $ */
  19.  
  20. #ifndef ISC_SOCKET_H
  21. #define ISC_SOCKET_H 1
  22.  
  23. /*****
  24.  ***** Module Info
  25.  *****/
  26.  
  27. /*! \file
  28.  * \brief Provides TCP and UDP sockets for network I/O.  The sockets are event
  29.  * sources in the task system.
  30.  *
  31.  * When I/O completes, a completion event for the socket is posted to the
  32.  * event queue of the task which requested the I/O.
  33.  *
  34.  * \li MP:
  35.  *    The module ensures appropriate synchronization of data structures it
  36.  *    creates and manipulates.
  37.  *    Clients of this module must not be holding a socket's task's lock when
  38.  *    making a call that affects that socket.  Failure to follow this rule
  39.  *    can result in deadlock.
  40.  *    The caller must ensure that isc_socketmgr_destroy() is called only
  41.  *    once for a given manager.
  42.  *
  43.  * \li Reliability:
  44.  *    No anticipated impact.
  45.  *
  46.  * \li Resources:
  47.  *    TBS
  48.  *
  49.  * \li Security:
  50.  *    No anticipated impact.
  51.  *
  52.  * \li Standards:
  53.  *    None.
  54.  */
  55.  
  56. /***
  57.  *** Imports
  58.  ***/
  59.  
  60. #include <isc/lang.h>
  61. #include <isc/types.h>
  62. #include <isc/event.h>
  63. #include <isc/eventclass.h>
  64. #include <isc/time.h>
  65. #include <isc/region.h>
  66. #include <isc/sockaddr.h>
  67.  
  68. ISC_LANG_BEGINDECLS
  69.  
  70. /***
  71.  *** Constants
  72.  ***/
  73.  
  74. /*%
  75.  * Maximum number of buffers in a scatter/gather read/write.  The operating
  76.  * system in use must support at least this number (plus one on some.)
  77.  */
  78. #define ISC_SOCKET_MAXSCATTERGATHER    8
  79.  
  80. /*%
  81.  * In isc_socket_bind() set socket option SO_REUSEADDR prior to calling
  82.  * bind() if a non zero port is specified (AF_INET and AF_INET6).
  83.  */
  84. #define ISC_SOCKET_REUSEADDRESS        0x01U
  85.  
  86. /***
  87.  *** Types
  88.  ***/
  89.  
  90. struct isc_socketevent {
  91.     ISC_EVENT_COMMON(isc_socketevent_t);
  92.     isc_result_t        result;        /*%< OK, EOF, whatever else */
  93.     unsigned int        minimum;    /*%< minimum i/o for event */
  94.     unsigned int        n;        /*%< bytes read or written */
  95.     unsigned int        offset;        /*%< offset into buffer list */
  96.     isc_region_t        region;        /*%< for single-buffer i/o */
  97.     isc_bufferlist_t    bufferlist;    /*%< list of buffers */
  98.     isc_sockaddr_t        address;    /*%< source address */
  99.     isc_time_t        timestamp;    /*%< timestamp of packet recv */
  100.     struct in6_pktinfo    pktinfo;    /*%< ipv6 pktinfo */
  101.     isc_uint32_t        attributes;    /*%< see below */
  102.     isc_eventdestructor_t   destroy;    /*%< original destructor */
  103. };
  104.  
  105. typedef struct isc_socket_newconnev isc_socket_newconnev_t;
  106. struct isc_socket_newconnev {
  107.     ISC_EVENT_COMMON(isc_socket_newconnev_t);
  108.     isc_socket_t *        newsocket;
  109.     isc_result_t        result;        /*%< OK, EOF, whatever else */
  110.     isc_sockaddr_t        address;    /*%< source address */
  111. };
  112.  
  113. typedef struct isc_socket_connev isc_socket_connev_t;
  114. struct isc_socket_connev {
  115.     ISC_EVENT_COMMON(isc_socket_connev_t);
  116.     isc_result_t        result;        /*%< OK, EOF, whatever else */
  117. };
  118.  
  119. /*@{*/
  120. /*!
  121.  * _ATTACHED:    Internal use only.
  122.  * _TRUNC:    Packet was truncated on receive.
  123.  * _CTRUNC:    Packet control information was truncated.  This can
  124.  *        indicate that the packet is not complete, even though
  125.  *        all the data is valid.
  126.  * _TIMESTAMP:    The timestamp member is valid.
  127.  * _PKTINFO:    The pktinfo member is valid.
  128.  * _MULTICAST:    The UDP packet was received via a multicast transmission.
  129.  */
  130. #define ISC_SOCKEVENTATTR_ATTACHED        0x80000000U /* internal */
  131. #define ISC_SOCKEVENTATTR_TRUNC            0x00800000U /* public */
  132. #define ISC_SOCKEVENTATTR_CTRUNC        0x00400000U /* public */
  133. #define ISC_SOCKEVENTATTR_TIMESTAMP        0x00200000U /* public */
  134. #define ISC_SOCKEVENTATTR_PKTINFO        0x00100000U /* public */
  135. #define ISC_SOCKEVENTATTR_MULTICAST        0x00080000U /* public */
  136. /*@}*/
  137.  
  138. #define ISC_SOCKEVENT_ANYEVENT  (0)
  139. #define ISC_SOCKEVENT_RECVDONE    (ISC_EVENTCLASS_SOCKET + 1)
  140. #define ISC_SOCKEVENT_SENDDONE    (ISC_EVENTCLASS_SOCKET + 2)
  141. #define ISC_SOCKEVENT_NEWCONN    (ISC_EVENTCLASS_SOCKET + 3)
  142. #define ISC_SOCKEVENT_CONNECT    (ISC_EVENTCLASS_SOCKET + 4)
  143.  
  144. /*
  145.  * Internal events.
  146.  */
  147. #define ISC_SOCKEVENT_INTR    (ISC_EVENTCLASS_SOCKET + 256)
  148. #define ISC_SOCKEVENT_INTW    (ISC_EVENTCLASS_SOCKET + 257)
  149.  
  150. typedef enum {
  151.     isc_sockettype_udp = 1,
  152.     isc_sockettype_tcp = 2,
  153.     isc_sockettype_unix = 3
  154. } isc_sockettype_t;
  155.  
  156. /*@{*/
  157. /*!
  158.  * How a socket should be shutdown in isc_socket_shutdown() calls.
  159.  */
  160. #define ISC_SOCKSHUT_RECV    0x00000001    /*%< close read side */
  161. #define ISC_SOCKSHUT_SEND    0x00000002    /*%< close write side */
  162. #define ISC_SOCKSHUT_ALL    0x00000003    /*%< close them all */
  163. /*@}*/
  164.  
  165. /*@{*/
  166. /*!
  167.  * What I/O events to cancel in isc_socket_cancel() calls.
  168.  */
  169. #define ISC_SOCKCANCEL_RECV    0x00000001    /*%< cancel recv */
  170. #define ISC_SOCKCANCEL_SEND    0x00000002    /*%< cancel send */
  171. #define ISC_SOCKCANCEL_ACCEPT    0x00000004    /*%< cancel accept */
  172. #define ISC_SOCKCANCEL_CONNECT    0x00000008    /*%< cancel connect */
  173. #define ISC_SOCKCANCEL_ALL    0x0000000f    /*%< cancel everything */
  174. /*@}*/
  175.  
  176. /*@{*/
  177. /*!
  178.  * Flags for isc_socket_send() and isc_socket_recv() calls.
  179.  */
  180. #define ISC_SOCKFLAG_IMMEDIATE    0x00000001    /*%< send event only if needed */
  181. #define ISC_SOCKFLAG_NORETRY    0x00000002    /*%< drop failed UDP sends */
  182. /*@}*/
  183.  
  184. /***
  185.  *** Socket and Socket Manager Functions
  186.  ***
  187.  *** Note: all Ensures conditions apply only if the result is success for
  188.  *** those functions which return an isc_result.
  189.  ***/
  190.  
  191. isc_result_t
  192. isc_socket_create(isc_socketmgr_t *manager,
  193.           int pf,
  194.           isc_sockettype_t type,
  195.           isc_socket_t **socketp);
  196. /*%<
  197.  * Create a new 'type' socket managed by 'manager'.
  198.  *
  199.  * Note:
  200.  *
  201.  *\li    'pf' is the desired protocol family, e.g. PF_INET or PF_INET6.
  202.  *
  203.  * Requires:
  204.  *
  205.  *\li    'manager' is a valid manager
  206.  *
  207.  *\li    'socketp' is a valid pointer, and *socketp == NULL
  208.  *
  209.  * Ensures:
  210.  *
  211.  *    '*socketp' is attached to the newly created socket
  212.  *
  213.  * Returns:
  214.  *
  215.  *\li    #ISC_R_SUCCESS
  216.  *\li    #ISC_R_NOMEMORY
  217.  *\li    #ISC_R_NORESOURCES
  218.  *\li    #ISC_R_UNEXPECTED
  219.  */
  220.  
  221. void
  222. isc_socket_cancel(isc_socket_t *sock, isc_task_t *task,
  223.           unsigned int how);
  224. /*%<
  225.  * Cancel pending I/O of the type specified by "how".
  226.  *
  227.  * Note: if "task" is NULL, then the cancel applies to all tasks using the
  228.  * socket.
  229.  *
  230.  * Requires:
  231.  *
  232.  * \li    "socket" is a valid socket
  233.  *
  234.  * \li    "task" is NULL or a valid task
  235.  *
  236.  * "how" is a bitmask describing the type of cancelation to perform.
  237.  * The type ISC_SOCKCANCEL_ALL will cancel all pending I/O on this
  238.  * socket.
  239.  *
  240.  * \li ISC_SOCKCANCEL_RECV:
  241.  *    Cancel pending isc_socket_recv() calls.
  242.  *
  243.  * \li ISC_SOCKCANCEL_SEND:
  244.  *    Cancel pending isc_socket_send() and isc_socket_sendto() calls.
  245.  *
  246.  * \li ISC_SOCKCANCEL_ACCEPT:
  247.  *    Cancel pending isc_socket_accept() calls.
  248.  *
  249.  * \li ISC_SOCKCANCEL_CONNECT:
  250.  *    Cancel pending isc_socket_connect() call.
  251.  */
  252.  
  253. void
  254. isc_socket_shutdown(isc_socket_t *sock, unsigned int how);
  255. /*%<
  256.  * Shutdown 'socket' according to 'how'.
  257.  *
  258.  * Requires:
  259.  *
  260.  * \li    'socket' is a valid socket.
  261.  *
  262.  * \li    'task' is NULL or is a valid task.
  263.  *
  264.  * \li    If 'how' is 'ISC_SOCKSHUT_RECV' or 'ISC_SOCKSHUT_ALL' then
  265.  *
  266.  *        The read queue must be empty.
  267.  *
  268.  *        No further read requests may be made.
  269.  *
  270.  * \li    If 'how' is 'ISC_SOCKSHUT_SEND' or 'ISC_SOCKSHUT_ALL' then
  271.  *
  272.  *        The write queue must be empty.
  273.  *
  274.  *        No further write requests may be made.
  275.  */
  276.  
  277. void
  278. isc_socket_attach(isc_socket_t *sock, isc_socket_t **socketp);
  279. /*%<
  280.  * Attach *socketp to socket.
  281.  *
  282.  * Requires:
  283.  *
  284.  * \li    'socket' is a valid socket.
  285.  *
  286.  * \li    'socketp' points to a NULL socket.
  287.  *
  288.  * Ensures:
  289.  *
  290.  * \li    *socketp is attached to socket.
  291.  */
  292.  
  293. void
  294. isc_socket_detach(isc_socket_t **socketp);
  295. /*%<
  296.  * Detach *socketp from its socket.
  297.  *
  298.  * Requires:
  299.  *
  300.  * \li    'socketp' points to a valid socket.
  301.  *
  302.  * \li    If '*socketp' is the last reference to the socket,
  303.  *    then:
  304.  *
  305.  *        There must be no pending I/O requests.
  306.  *
  307.  * Ensures:
  308.  *
  309.  * \li    *socketp is NULL.
  310.  *
  311.  * \li    If '*socketp' is the last reference to the socket,
  312.  *    then:
  313.  *
  314.  *        The socket will be shutdown (both reading and writing)
  315.  *        for all tasks.
  316.  *
  317.  *        All resources used by the socket have been freed
  318.  */
  319.  
  320. isc_result_t
  321. isc_socket_bind(isc_socket_t *sock, isc_sockaddr_t *addressp,
  322.             unsigned int options);
  323. /*%<
  324.  * Bind 'socket' to '*addressp'.
  325.  *
  326.  * Requires:
  327.  *
  328.  * \li    'socket' is a valid socket
  329.  *
  330.  * \li    'addressp' points to a valid isc_sockaddr.
  331.  *
  332.  * Returns:
  333.  *
  334.  * \li    ISC_R_SUCCESS
  335.  * \li    ISC_R_NOPERM
  336.  * \li    ISC_R_ADDRNOTAVAIL
  337.  * \li    ISC_R_ADDRINUSE
  338.  * \li    ISC_R_BOUND
  339.  * \li    ISC_R_UNEXPECTED
  340.  */
  341.  
  342. isc_result_t
  343. isc_socket_filter(isc_socket_t *sock, const char *filter);
  344. /*%<
  345.  * Inform the kernel that it should perform accept filtering.
  346.  * If filter is NULL the current filter will be removed.:w
  347.  */
  348.  
  349. isc_result_t
  350. isc_socket_listen(isc_socket_t *sock, unsigned int backlog);
  351. /*%<
  352.  * Set listen mode on the socket.  After this call, the only function that
  353.  * can be used (other than attach and detach) is isc_socket_accept().
  354.  *
  355.  * Notes:
  356.  *
  357.  * \li    'backlog' is as in the UNIX system call listen() and may be
  358.  *    ignored by non-UNIX implementations.
  359.  *
  360.  * \li    If 'backlog' is zero, a reasonable system default is used, usually
  361.  *    SOMAXCONN.
  362.  *
  363.  * Requires:
  364.  *
  365.  * \li    'socket' is a valid, bound TCP socket or a valid, bound UNIX socket.
  366.  *
  367.  * Returns:
  368.  *
  369.  * \li    ISC_R_SUCCESS
  370.  * \li    ISC_R_UNEXPECTED
  371.  */
  372.  
  373. isc_result_t
  374. isc_socket_accept(isc_socket_t *sock,
  375.           isc_task_t *task, isc_taskaction_t action, const void *arg);
  376. /*%<
  377.  * Queue accept event.  When a new connection is received, the task will
  378.  * get an ISC_SOCKEVENT_NEWCONN event with the sender set to the listen
  379.  * socket.  The new socket structure is sent inside the isc_socket_newconnev_t
  380.  * event type, and is attached to the task 'task'.
  381.  *
  382.  * REQUIRES:
  383.  * \li    'socket' is a valid TCP socket that isc_socket_listen() was called
  384.  *    on.
  385.  *
  386.  * \li    'task' is a valid task
  387.  *
  388.  * \li    'action' is a valid action
  389.  *
  390.  * RETURNS:
  391.  * \li    ISC_R_SUCCESS
  392.  * \li    ISC_R_NOMEMORY
  393.  * \li    ISC_R_UNEXPECTED
  394.  */
  395.  
  396. isc_result_t
  397. isc_socket_connect(isc_socket_t *sock, isc_sockaddr_t *addressp,
  398.            isc_task_t *task, isc_taskaction_t action,
  399.            const void *arg);
  400. /*%<
  401.  * Connect 'socket' to peer with address *saddr.  When the connection
  402.  * succeeds, or when an error occurs, a CONNECT event with action 'action'
  403.  * and arg 'arg' will be posted to the event queue for 'task'.
  404.  *
  405.  * Requires:
  406.  *
  407.  * \li    'socket' is a valid TCP socket
  408.  *
  409.  * \li    'addressp' points to a valid isc_sockaddr
  410.  *
  411.  * \li    'task' is a valid task
  412.  *
  413.  * \li    'action' is a valid action
  414.  *
  415.  * Returns:
  416.  *
  417.  * \li    ISC_R_SUCCESS
  418.  * \li    ISC_R_NOMEMORY
  419.  * \li    ISC_R_UNEXPECTED
  420.  *
  421.  * Posted event's result code:
  422.  *
  423.  * \li    ISC_R_SUCCESS
  424.  * \li    ISC_R_TIMEDOUT
  425.  * \li    ISC_R_CONNREFUSED
  426.  * \li    ISC_R_NETUNREACH
  427.  * \li    ISC_R_UNEXPECTED
  428.  */
  429.  
  430. isc_result_t
  431. isc_socket_getpeername(isc_socket_t *sock, isc_sockaddr_t *addressp);
  432. /*%<
  433.  * Get the name of the peer connected to 'socket'.
  434.  *
  435.  * Requires:
  436.  *
  437.  * \li    'socket' is a valid TCP socket.
  438.  *
  439.  * Returns:
  440.  *
  441.  * \li    ISC_R_SUCCESS
  442.  * \li    ISC_R_TOOSMALL
  443.  * \li    ISC_R_UNEXPECTED
  444.  */
  445.  
  446. isc_result_t
  447. isc_socket_getsockname(isc_socket_t *sock, isc_sockaddr_t *addressp);
  448. /*%<
  449.  * Get the name of 'socket'.
  450.  *
  451.  * Requires:
  452.  *
  453.  * \li    'socket' is a valid socket.
  454.  *
  455.  * Returns:
  456.  *
  457.  * \li    ISC_R_SUCCESS
  458.  * \li    ISC_R_TOOSMALL
  459.  * \li    ISC_R_UNEXPECTED
  460.  */
  461.  
  462. /*@{*/
  463. isc_result_t
  464. isc_socket_recv(isc_socket_t *sock, isc_region_t *region,
  465.         unsigned int minimum,
  466.         isc_task_t *task, isc_taskaction_t action, const void *arg);
  467. isc_result_t
  468. isc_socket_recvv(isc_socket_t *sock, isc_bufferlist_t *buflist,
  469.          unsigned int minimum,
  470.          isc_task_t *task, isc_taskaction_t action, const void *arg);
  471.  
  472. isc_result_t
  473. isc_socket_recv2(isc_socket_t *sock, isc_region_t *region,
  474.          unsigned int minimum, isc_task_t *task,
  475.          isc_socketevent_t *event, unsigned int flags);
  476.  
  477. /*!
  478.  * Receive from 'socket', storing the results in region.
  479.  *
  480.  * Notes:
  481.  *
  482.  *\li    Let 'length' refer to the length of 'region' or to the sum of all
  483.  *    available regions in the list of buffers '*buflist'.
  484.  *
  485.  *\li    If 'minimum' is non-zero and at least that many bytes are read,
  486.  *    the completion event will be posted to the task 'task.'  If minimum
  487.  *    is zero, the exact number of bytes requested in the region must
  488.  *     be read for an event to be posted.  This only makes sense for TCP
  489.  *    connections, and is always set to 1 byte for UDP.
  490.  *
  491.  *\li    The read will complete when the desired number of bytes have been
  492.  *    read, if end-of-input occurs, or if an error occurs.  A read done
  493.  *    event with the given 'action' and 'arg' will be posted to the
  494.  *    event queue of 'task'.
  495.  *
  496.  *\li    The caller may not modify 'region', the buffers which are passed
  497.  *    into this function, or any data they refer to until the completion
  498.  *    event is received.
  499.  *
  500.  *\li    For isc_socket_recvv():
  501.  *    On successful completion, '*buflist' will be empty, and the list of
  502.  *    all buffers will be returned in the done event's 'bufferlist'
  503.  *    member.  On error return, '*buflist' will be unchanged.
  504.  *
  505.  *\li    For isc_socket_recv2():
  506.  *    'event' is not NULL, and the non-socket specific fields are
  507.  *    expected to be initialized.
  508.  *
  509.  *\li    For isc_socket_recv2():
  510.  *    The only defined value for 'flags' is ISC_SOCKFLAG_IMMEDIATE.  If
  511.  *    set and the operation completes, the return value will be
  512.  *    ISC_R_SUCCESS and the event will be filled in and not sent.  If the
  513.  *    operation does not complete, the return value will be
  514.  *    ISC_R_INPROGRESS and the event will be sent when the operation
  515.  *    completes.
  516.  *
  517.  * Requires:
  518.  *
  519.  *\li    'socket' is a valid, bound socket.
  520.  *
  521.  *\li    For isc_socket_recv():
  522.  *    'region' is a valid region
  523.  *
  524.  *\li    For isc_socket_recvv():
  525.  *    'buflist' is non-NULL, and '*buflist' contain at least one buffer.
  526.  *
  527.  *\li    'task' is a valid task
  528.  *
  529.  *\li    For isc_socket_recv() and isc_socket_recvv():
  530.  *    action != NULL and is a valid action
  531.  *
  532.  *\li    For isc_socket_recv2():
  533.  *    event != NULL
  534.  *
  535.  * Returns:
  536.  *
  537.  *\li    #ISC_R_SUCCESS
  538.  *\li    #ISC_R_INPROGRESS
  539.  *\li    #ISC_R_NOMEMORY
  540.  *\li    #ISC_R_UNEXPECTED
  541.  *
  542.  * Event results:
  543.  *
  544.  *\li    #ISC_R_SUCCESS
  545.  *\li    #ISC_R_UNEXPECTED
  546.  *\li    XXX needs other net-type errors
  547.  */
  548. /*@}*/
  549.  
  550. /*@{*/
  551. isc_result_t
  552. isc_socket_send(isc_socket_t *sock, isc_region_t *region,
  553.         isc_task_t *task, isc_taskaction_t action, const void *arg);
  554. isc_result_t
  555. isc_socket_sendto(isc_socket_t *sock, isc_region_t *region,
  556.           isc_task_t *task, isc_taskaction_t action, const void *arg,
  557.           isc_sockaddr_t *address, struct in6_pktinfo *pktinfo);
  558. isc_result_t
  559. isc_socket_sendv(isc_socket_t *sock, isc_bufferlist_t *buflist,
  560.          isc_task_t *task, isc_taskaction_t action, const void *arg);
  561. isc_result_t
  562. isc_socket_sendtov(isc_socket_t *sock, isc_bufferlist_t *buflist,
  563.            isc_task_t *task, isc_taskaction_t action, const void *arg,
  564.            isc_sockaddr_t *address, struct in6_pktinfo *pktinfo);
  565. isc_result_t
  566. isc_socket_sendto2(isc_socket_t *sock, isc_region_t *region,
  567.            isc_task_t *task,
  568.            isc_sockaddr_t *address, struct in6_pktinfo *pktinfo,
  569.            isc_socketevent_t *event, unsigned int flags);
  570.  
  571. /*!
  572.  * Send the contents of 'region' to the socket's peer.
  573.  *
  574.  * Notes:
  575.  *
  576.  *\li    Shutting down the requestor's task *may* result in any
  577.  *    still pending writes being dropped or completed, depending on the
  578.  *    underlying OS implementation.
  579.  *
  580.  *\li    If 'action' is NULL, then no completion event will be posted.
  581.  *
  582.  *\li    The caller may not modify 'region', the buffers which are passed
  583.  *    into this function, or any data they refer to until the completion
  584.  *    event is received.
  585.  *
  586.  *\li    For isc_socket_sendv() and isc_socket_sendtov():
  587.  *    On successful completion, '*buflist' will be empty, and the list of
  588.  *    all buffers will be returned in the done event's 'bufferlist'
  589.  *    member.  On error return, '*buflist' will be unchanged.
  590.  *
  591.  *\li    For isc_socket_sendto2():
  592.  *    'event' is not NULL, and the non-socket specific fields are
  593.  *    expected to be initialized.
  594.  *
  595.  *\li    For isc_socket_sendto2():
  596.  *    The only defined values for 'flags' are ISC_SOCKFLAG_IMMEDIATE
  597.  *    and ISC_SOCKFLAG_NORETRY.
  598.  *
  599.  *\li    If ISC_SOCKFLAG_IMMEDIATE is set and the operation completes, the
  600.  *    return value will be ISC_R_SUCCESS and the event will be filled
  601.  *    in and not sent.  If the operation does not complete, the return
  602.  *    value will be ISC_R_INPROGRESS and the event will be sent when
  603.  *    the operation completes.
  604.  *
  605.  *\li    ISC_SOCKFLAG_NORETRY can only be set for UDP sockets.  If set
  606.  *    and the send operation fails due to a transient error, the send
  607.  *    will not be retried and the error will be indicated in the event.
  608.  *    Using this option along with ISC_SOCKFLAG_IMMEDIATE allows the caller
  609.  *    to specify a region that is allocated on the stack.
  610.  *
  611.  * Requires:
  612.  *
  613.  *\li    'socket' is a valid, bound socket.
  614.  *
  615.  *\li    For isc_socket_send():
  616.  *    'region' is a valid region
  617.  *
  618.  *\li    For isc_socket_sendv() and isc_socket_sendtov():
  619.  *    'buflist' is non-NULL, and '*buflist' contain at least one buffer.
  620.  *
  621.  *\li    'task' is a valid task
  622.  *
  623.  *\li    For isc_socket_sendv(), isc_socket_sendtov(), isc_socket_send(), and
  624.  *    isc_socket_sendto():
  625.  *    action == NULL or is a valid action
  626.  *
  627.  *\li    For isc_socket_sendto2():
  628.  *    event != NULL
  629.  *
  630.  * Returns:
  631.  *
  632.  *\li    #ISC_R_SUCCESS
  633.  *\li    #ISC_R_INPROGRESS
  634.  *\li    #ISC_R_NOMEMORY
  635.  *\li    #ISC_R_UNEXPECTED
  636.  *
  637.  * Event results:
  638.  *
  639.  *\li    #ISC_R_SUCCESS
  640.  *\li    #ISC_R_UNEXPECTED
  641.  *\li    XXX needs other net-type errors
  642.  */
  643. /*@}*/
  644.  
  645. isc_result_t
  646. isc_socketmgr_create(isc_mem_t *mctx, isc_socketmgr_t **managerp);
  647. /*%<
  648.  * Create a socket manager.
  649.  *
  650.  * Notes:
  651.  *
  652.  *\li    All memory will be allocated in memory context 'mctx'.
  653.  *
  654.  * Requires:
  655.  *
  656.  *\li    'mctx' is a valid memory context.
  657.  *
  658.  *\li    'managerp' points to a NULL isc_socketmgr_t.
  659.  *
  660.  * Ensures:
  661.  *
  662.  *\li    '*managerp' is a valid isc_socketmgr_t.
  663.  *
  664.  * Returns:
  665.  *
  666.  *\li    #ISC_R_SUCCESS
  667.  *\li    #ISC_R_NOMEMORY
  668.  *\li    #ISC_R_UNEXPECTED
  669.  */
  670.  
  671. void
  672. isc_socketmgr_destroy(isc_socketmgr_t **managerp);
  673. /*%<
  674.  * Destroy a socket manager.
  675.  *
  676.  * Notes:
  677.  *
  678.  *\li    This routine blocks until there are no sockets left in the manager,
  679.  *    so if the caller holds any socket references using the manager, it
  680.  *    must detach them before calling isc_socketmgr_destroy() or it will
  681.  *    block forever.
  682.  *
  683.  * Requires:
  684.  *
  685.  *\li    '*managerp' is a valid isc_socketmgr_t.
  686.  *
  687.  *\li    All sockets managed by this manager are fully detached.
  688.  *
  689.  * Ensures:
  690.  *
  691.  *\li    *managerp == NULL
  692.  *
  693.  *\li    All resources used by the manager have been freed.
  694.  */
  695.  
  696. isc_sockettype_t
  697. isc_socket_gettype(isc_socket_t *sock);
  698. /*%<
  699.  * Returns the socket type for "sock."
  700.  *
  701.  * Requires:
  702.  *
  703.  *\li    "sock" is a valid socket.
  704.  */
  705.  
  706. /*@{*/
  707. isc_boolean_t
  708. isc_socket_isbound(isc_socket_t *sock);
  709.  
  710. void
  711. isc_socket_ipv6only(isc_socket_t *sock, isc_boolean_t yes);
  712. /*%<
  713.  * If the socket is an IPv6 socket set/clear the IPV6_IPV6ONLY socket
  714.  * option if the host OS supports this option.
  715.  *
  716.  * Requires:
  717.  *\li    'sock' is a valid socket.
  718.  */
  719. /*@}*/
  720.  
  721. void
  722. isc_socket_cleanunix(isc_sockaddr_t *addr, isc_boolean_t active);
  723.  
  724. /*%<
  725.  * Cleanup UNIX domain sockets in the file-system.  If 'active' is true
  726.  * then just unlink the socket.  If 'active' is false try to determine
  727.  * if there is a listener of the socket or not.  If no listener is found
  728.  * then unlink socket.
  729.  *
  730.  * Prior to unlinking the path is tested to see if it a socket.
  731.  *
  732.  * Note: there are a number of race conditions which cannot be avoided
  733.  *       both in the filesystem and any application using UNIX domain
  734.  *     sockets (e.g. socket is tested between bind() and listen(),
  735.  *     the socket is deleted and replaced in the file-system between
  736.  *     stat() and unlink()).
  737.  */
  738.  
  739. isc_result_t
  740. isc_socket_permunix(isc_sockaddr_t *sockaddr, isc_uint32_t perm,
  741.                     isc_uint32_t owner, isc_uint32_t group);
  742. /*%<
  743.  * Set ownership and file permissions on the UNIX domain socket.
  744.  *
  745.  * Note: On Solaris and SunOS this secures the directory containing
  746.  *       the socket as Solaris and SunOS do not honour the filesytem
  747.  *     permissions on the socket.
  748.  *
  749.  * Requires:
  750.  * \li    'sockaddr' to be a valid UNIX domain sockaddr.
  751.  *
  752.  * Returns:
  753.  * \li    #ISC_R_SUCCESS
  754.  * \li    #ISC_R_FAILURE
  755.  */
  756.  
  757. void
  758. isc__socketmgr_setreserved(isc_socketmgr_t *mgr, isc_uint32_t);
  759. /*%<
  760.  * Temporary.  For use by named only.
  761.  */
  762.  
  763. ISC_LANG_ENDDECLS
  764.  
  765. #endif /* ISC_SOCKET_H */
  766.